#!/usr/bin/env python3
"""
GomerX 智能机器人启动脚本
提供简化的命令行界面

这个脚本作为GomerX机器人控制系统的用户友好入口点，
简化了安装依赖、运行测试、配置参数和启动机器人等操作。
它通过调用main.py来实现实际功能，同时提供更简洁的命令行接口。
"""

# 导入标准库
import os         # 操作系统模块，用于文件路径操作
import sys        # 系统模块，用于访问系统相关功能
import argparse   # 命令行参数解析模块，用于处理命令行输入
import subprocess # 子进程模块，用于执行外部命令

def run_command(cmd, description):
    """
    运行命令并显示描述
    
    这个函数封装了subprocess.run，提供统一的命令执行界面，
    包括命令描述显示、错误处理和用户反馈。
    
    Args:
        cmd: 要执行的命令列表，格式为[可执行文件, 参数1, 参数2, ...]
        description: 命令的描述性文本，用于向用户解释命令的作用
        
    Returns:
        bool: 如果命令成功执行返回True，否则返回False
    """
    # 打印命令执行信息
    # 使用等号线创建视觉分隔，使输出更清晰易读
    print(f"\n{'='*50}")
    print(f"执行: {description}")  # 显示命令描述
    print(f"命令: {' '.join(cmd)}")  # 显示实际执行的命令
    print(f"{'='*50}")
    
    try:
        # 执行命令
        # subprocess.run会等待命令完成，并检查返回码
        # check=True表示如果命令返回非零退出码，会抛出CalledProcessError异常
        subprocess.run(cmd, check=True)
        print("\n执行成功!")  # 命令成功完成时的反馈
    except subprocess.CalledProcessError as e:
        # 捕获命令执行失败的异常
        # CalledProcessError在命令返回非零退出码时抛出
        print(f"\n执行失败: {e}")  # 显示错误信息
        return False
    except KeyboardInterrupt:
        # 捕获用户中断信号（Ctrl+C）
        print("\n用户中断执行")  # 显示中断信息
        return False
    
    return True  # 命令成功执行完成

def main():
    """
    主函数
    
    解析命令行参数，根据用户指定的模式执行相应的操作。
    支持的模式包括：
    - install: 安装项目依赖
    - test: 运行测试脚本
    - config: 进入配置模式
    - auto: 启动自动模式
    - manual: 启动手动模式
    """
    # 创建命令行参数解析器
    # argparse模块提供了强大的命令行参数解析功能
    parser = argparse.ArgumentParser(description="GomerX 智能机器人启动脚本")
    
    # 添加模式参数
    # choices参数限制了可接受的值范围，default参数设置了默认值
    parser.add_argument("--mode", choices=["auto", "manual", "config", "install", "test"], 
                       default="auto", help="运行模式")
    
    # 添加日志级别参数
    # 这个参数会传递给main.py，控制日志输出的详细程度
    parser.add_argument("--log-level", choices=["debug", "info", "warning", "error"], 
                       default="info", help="日志级别")
    
    # 解析命令行参数
    args = parser.parse_args()
    
    # 获取脚本所在目录
    # 使用os.path.dirname和os.path.abspath获取当前脚本的绝对路径目录
    # 这样可以确保无论从哪个目录运行脚本，都能正确找到相关文件
    script_dir = os.path.dirname(os.path.abspath(__file__))
    
    # 构建主程序路径
    # 主程序main.py位于同一目录下
    main_script = os.path.join(script_dir, "main.py")
    
    # 检查主程序是否存在
    # 在执行前检查文件是否存在，提供友好的错误信息
    if not os.path.exists(main_script):
        print(f"错误: 找不到主程序 {main_script}")
        return
    
    # 根据模式执行相应操作
    if args.mode == "install":
        # 安装依赖模式
        # 构建requirements.txt文件路径
        requirements_file = os.path.join(script_dir, "requirements.txt")
        
        # 检查requirements.txt是否存在
        if os.path.exists(requirements_file):
            # 构建pip安装命令
            # 使用sys.executable确保使用当前Python解释器
            cmd = [sys.executable, "-m", "pip", "install", "-r", requirements_file]
            run_command(cmd, "安装项目依赖")  # 执行安装命令
        else:
            print("错误: 找不到 requirements.txt 文件")
    
    elif args.mode == "test":
        # 测试模式
        # 构建测试脚本路径
        test_script = os.path.join(script_dir, "test.py")
        
        # 检查测试脚本是否存在
        if os.path.exists(test_script):
            # 构建测试命令
            cmd = [sys.executable, test_script]
            run_command(cmd, "运行测试")  # 执行测试命令
        else:
            print("警告: 找不到测试脚本 test.py")
    
    elif args.mode == "config":
        # 配置模式
        # 构建配置命令，调用main.py的配置模式
        cmd = [sys.executable, main_script, "--mode", "config"]
        run_command(cmd, "配置机器人参数")  # 执行配置命令
    
    else:
        # 自动或手动模式
        # 构建主程序命令，传递模式和日志级别参数
        cmd = [
            sys.executable, main_script,
            "--mode", args.mode,
            "--log-level", args.log_level
        ]
        
        # 根据模式生成描述文本
        mode_desc = "自动模式" if args.mode == "auto" else "手动模式"
        run_command(cmd, f"启动{mode_desc}")  # 执行启动命令

# 程序入口点
# 当直接运行此文件时，执行main函数
if __name__ == "__main__":
    main()